﻿using System.Text.Json.Serialization;

namespace Sage.CloudStorage.Qiniu.Models
{
    /// <summary>
    /// 上传分片响应类
    /// 包含单个分片上传成功后七牛云返回的验证信息
    /// </summary>
    /// <remarks>
    /// **分片上传验证**：
    /// - 每个分片上传成功后都会返回此响应
    /// - 包含分片的唯一标识和完整性验证信息
    /// - 用于后续完成上传时的分片验证
    /// 
    /// **数据完整性**：
    /// - ETag用于验证分片数据完整性
    /// - MD5提供额外的数据校验
    /// - 确保上传过程中数据未损坏
    /// 
    /// **使用场景**：
    /// - 记录已成功上传的分片信息
    /// - 完成分片上传时提供分片列表
    /// - 断点续传时验证已上传分片
    /// - 数据完整性校验和故障排查
    /// </remarks>
    public class UploadPartResponse
    {
        /// <summary>
        /// 上传分片内容的ETag值
        /// 用来标识分片，完成分片上传时作为参数进行文件合成
        /// </summary>
        /// <remarks>
        /// **ETag特性**：
        /// - 由七牛云服务器计算生成的唯一标识
        /// - 基于分片内容计算，内容相同则ETag相同
        /// - 长度通常为28个字符的Base64编码字符串
        /// - 用于分片的唯一标识和完整性验证
        /// 
        /// **使用用途**：
        /// - **完成上传**：在CompleteMultipartUpload请求中必须提供
        /// - **分片验证**：验证分片数据是否完整和正确
        /// - **断点续传**：识别已上传的分片，避免重复上传
        /// - **数据校验**：确保分片在传输过程中未被篡改
        /// 
        /// **存储要求**：
        /// - 必须与对应的分片号(PartNumber)一起保存
        /// - 用于构建CompletePartInfo列表
        /// - 建议持久化存储，支持断点续传
        /// 
        /// **格式示例**：
        /// "FqvtxHpe3j-rEzkImMUWDsmvu27D"
        /// 
        /// **重要说明**：
        /// - ETag值在完成上传时必须准确提供
        /// - 如果ETag不匹配，完成上传会失败
        /// - 不同分片的ETag值必然不同（除非内容完全相同）
        /// </remarks>
        [JsonPropertyName("etag")]
        public string Etag { get; set; } = "";

        /// <summary>
        /// 上传分片内容的MD5值
        /// 提供额外的数据完整性验证
        /// </summary>
        /// <remarks>
        /// **MD5校验**：
        /// - 标准MD5哈希算法计算的分片内容摘要
        /// - 32个字符的十六进制字符串
        /// - 用于客户端验证分片数据完整性
        /// - 可以与客户端计算的MD5值进行比对
        /// 
        /// **应用场景**：
        /// - **数据验证**：客户端可以计算本地分片的MD5并比对
        /// - **传输校验**：确保网络传输过程中数据未损坏
        /// - **调试诊断**：出现问题时用于数据完整性分析
        /// - **日志记录**：记录上传分片的详细信息
        /// 
        /// **使用方法**：
        /// ```csharp
        /// // 客户端计算分片MD5
        /// using var md5 = MD5.Create();
        /// var localMd5 = Convert.ToHexString(md5.ComputeHash(partData)).ToLower();
        /// 
        /// // 与服务器返回的MD5比对
        /// if (localMd5 == response.Md5)
        /// {
        ///     Console.WriteLine("分片数据完整性验证通过");
        /// }
        /// ```
        /// 
        /// **格式示例**：
        /// "4f4acc5d8c71f5fbf04dace00b5360c8"
        /// 
        /// **最佳实践**：
        /// - 建议在客户端也计算MD5进行双重验证
        /// - 可以用于网络传输质量的监控
        /// - 在高可靠性要求的场景中启用MD5校验
        /// - 记录MD5值便于后续的数据审计
        /// </remarks>
        [JsonPropertyName("md5")]
        public string Md5 { get; set; } = "";
    }
}
